<body>
The compiler for the Dex  programming language.  When finished, Dex will be 
an imperative langauge that combines C-like syntax with LISP-like macros.

<h3>General Design Notes</h3>

The package dependencies go in this order:

<ol>
<li>{@link dex.misc}</li>
<li>{@link dex.compiler.model.base}</li>
<li>{@link dex.compiler.model.type}</li>
<li>{@link dex.compiler.model.expression}</li>
<li>{@link dex.compiler.model.statement}</li>
<li>{@link dex.compiler.model.definition}</li>
<li>{@link dex.compiler.parser}</li>
</ol>

There are no circular package dependencies; the <code>statement</code> package 
depends on the <code>expression</code> package, but the <code>expression</code>
package does not depend on <code>statement</code>.  I find this practice helps 
to separate concerns.

<p>The Visitor pattern is used throughout the model packages.  Each model 
package defines its own Visitor interface, which applies only to the classes
in that package.  The Visitor interfaces follow the package dependencies listed
above; eg, StatementVisitor extends ExpressionVisitor.  Thus a DefinitionVisitor
can touch any node in a Dex parse tree.  Eventually compiler phases like semantic 
analysis, macro execution and conversion to intermediate code will be implemented 
as visitors.

<p>The model classes are essentially read-only, which doesn't make much sense, since
macros should be able to alter the tree provided by the model.  But I found it useful 
to keep things read-only while building the parser.  I wasn't completely rigorous 
about that.  Internal collection fields can usually be mutated, for instance.  Eventually
every node will have to be fully mutable, but in the meantime the read-only approach
requires me to think through things a bit more.

<p>The {@link dex.misc.Mirror} class is a hack to prevent me from having to write 
a hundred <code>equals</code> and <code>hashCode</code> methods.  <code>Mirror</code>
requires that the JVM allow reflection to access private fields.

<h3>Status</h3>

The parser is almost complete, though I am still playing with new constructs.  Also,
some obvious things are missing, like <code>do { statement() } while condition</code>.

<p>The test coverage is a little sparse.  The TestParser.testEverything() method reads
in a silly input file (Everything.dex) that contains example syntax for every kind of
node.  The test loads the file, runs it through the parser to get a parse tree, 
converts the parse tree back into a string, then runs the parser on the new string
to get a new parse tree.  The two parse trees are then compared for equality.

<p>The test doesn't cover everything -- notably invalid input is never tested to make
sure it raises an exception -- but it does allow me to introduce changes to the 
parse tree nodes quickly, then run the tests to see if anything broke.

<p>The machine package is a bare-bones first stab at a "virtual virtual machine" in 
which to run macros.  I make no promises that the machine tests even work.

</body>